@dazzadev/vuetify-datatable 1.0.5 → 1.2.0

package/README.md

@@ -44,6 +44,123 @@ import { DataTable } from "@dazzadev/vuetify-datatable";
 </template>
 ```
 
+## Row Selection
+
+Set `showSelect` and bind `v-model` to hold the selected keys. **The key comes from `itemValue`**,
+so point it at whatever your bulk endpoint expects — not necessarily `id`.
+
+```vue
+<DataTable
+    v-model="selected"
+    :headers="headers"
+    :items="items"
+    :totalItems="totalItems"
+    item-value="uuid"
+    show-select
+    @onLoadData="loadData"
+>
+    <template #selection-actions="{ count, clear }">
+        <div v-if="count" class="d-flex align-center ga-2 pa-2">
+            <span>{{ count }} selected</span>
+            <v-btn size="small" @click="applyToSelection">Apply</v-btn>
+            <v-btn size="small" variant="text" @click="clear">Clear</v-btn>
+        </div>
+    </template>
+</DataTable>
+```
+
+`selectStrategy` decides what the header checkbox does: `page` marks the current page only, `all`
+marks every loaded row, `single` allows one row at a time. With server-side pagination `page` is
+usually what you want — the table only holds the rows it has fetched.
+
+## Wide Tables
+
+When the columns don't fit, the table helps the user find and keep what they need. Nothing of
+this shows while every column fits.
+
+- **Hidden columns indicator**: a fade on the side with more columns, a round arrow on the header
+  row that scrolls about 300 px, and a "Scroll to see more columns" hint above it until the first
+  scroll.
+- **Pinned actions column**: the header with key `actions` always goes last and sticks to the
+  right edge, with a shadow while columns pass under it.
+- **Column chooser**: a "Columns" button above the table to show, hide, search and reorder
+  columns (drag, or the arrow keys on the handle). It reads "Columns · N hidden" while columns are
+  hidden, and stays visible in that case even if the rest fits. `actions`, expand and select
+  columns are never listed.
+
+The choices are saved in `localStorage`, keyed by the set of header keys. Texts and the storage
+key can be set in the global config:
+
+```ts
+app.use(
+  createDataTableConfig({
+    texts: {
+      columns: () => i18n.global.t("dataTable.columns"),
+      hiddenColumns: (count) => i18n.global.t("dataTable.hiddenColumns", { count }, count),
+      scrollHint: "Desliza para ver más columnas",
+    },
+    storageKey: (key) => `${tenant}:${key}`,
+  }),
+);
+```
+
+Each text accepts a string or a function, which is read on every render so it follows the
+current locale. Available texts: `columns`, `hiddenColumns`, `searchColumns`, `showAllColumns`,
+`hideAllColumns`, `resetColumns`, `moveColumn`, `scrollHint`, `scrollLeft`, `scrollRight`.
+
+Attributes that are not props (`row-props`, `density`, `hover`…) are passed to the inner
+`v-data-table-server`.
+
+### Custom column chooser
+
+The `column-chooser` slot replaces the default button and dropdown, for example with a dialog.
+It is shown in the same place and under the same conditions as the default one. The table keeps
+the state and saves it; the slot only renders it.
+
+```vue
+<DataTable :headers="headers" :items="items" @onLoadData="loadData">
+  <template #column-chooser="{ columns, label, setVisible, move, reset }">
+    <v-btn size="small" @click="dialog = true">{{ label }}</v-btn>
+    <v-dialog v-model="dialog" max-width="420">
+      <v-card title="Columns">
+        <v-list>
+          <v-list-item v-for="column in columns" :key="column.key">
+            <v-checkbox-btn
+              :model-value="column.visible"
+              :label="column.title"
+              @update:model-value="setVisible(column.key, !!$event)"
+            />
+            <template #append>
+              <v-btn icon="mdi-arrow-up" variant="text" size="small" @click="move(column.key, -1)" />
+              <v-btn icon="mdi-arrow-down" variant="text" size="small" @click="move(column.key, 1)" />
+            </template>
+          </v-list-item>
+        </v-list>
+        <v-card-actions>
+          <v-btn @click="reset">Reset</v-btn>
+        </v-card-actions>
+      </v-card>
+    </v-dialog>
+  </template>
+</DataTable>
+```
+
+| Slot prop     | Type                                         | Description                                       |
+| ------------- | -------------------------------------------- | ------------------------------------------------- |
+| `columns`     | `DataTableColumn[]`                          | `{ key, title, visible }` in the current order    |
+| `hiddenCount` | `number`                                     | How many columns are hidden                       |
+| `label`       | `string`                                     | "Columns", or "Columns · N hidden"                |
+| `setVisible`  | `(key: string, visible: boolean) => void`    | Shows or hides one column                         |
+| `toggleAll`   | `() => void`                                 | Shows all, or hides all when every one is visible |
+| `move`        | `(key: string, step: -1 \| 1) => void`       | Moves a column one place up or down               |
+| `place`       | `(key: string, targetKey: string) => void`   | Moves a column to another one's position (drag)   |
+| `reset`       | `() => void`                                 | Restores the original order and visibility        |
+
+To only restyle the default chooser, target its classes: `.vdt-columns__button` (the button),
+`.vdt-columns` (the dropdown card), `.vdt-columns__list`, `.vdt-columns__item` and
+`.vdt-columns__handle`. The dropdown is rendered in Vuetify's overlay container, so its rules
+must not be scoped to the table.
+
 ## Icon Configuration
 
 Icons can be configured at 4 levels of priority (highest to lowest):
@@ -116,6 +233,9 @@ If no configuration is provided, the component uses Material Design Icons (inclu
 | `itemValue`                    | `string`        | `'id'`                     | Unique item identifier key             |
 | `tableClass`                   | `string`        | `'border rounded-md mt-5'` | CSS class for the table                |
 | `showExpand`                   | `boolean`       | `false`                    | Show expandable rows                   |
+| `showSelect`                   | `boolean`       | `false`                    | Show a checkbox column for row selection |
+| `selectStrategy`               | `'page' \| 'all' \| 'single'` | `'page'`       | How the header checkbox selects rows   |
+| `modelValue`                   | `(string \| number)[]` | `[]`               | Selected keys, taken from `itemValue`. Use with `v-model` |
 | `showViewButton`               | `boolean`       | `false`                    | Show view action button                |
 | `showEditButton`               | `boolean`       | `true`                     | Show edit action button                |
 | `showDeleteButton`             | `boolean`       | `true`                     | Show delete action button              |
@@ -141,6 +261,7 @@ If no configuration is provided, the component uses Material Design Icons (inclu
 | `editItem`   | `T`              | Triggered when edit button is clicked            |
 | `deleteItem` | `T`              | Triggered when delete is confirmed               |
 | `viewItem`   | `T`              | Triggered when view button is clicked            |
+| `update:modelValue` | `(string \| number)[]` | Triggered when the selection changes    |
 
 ## Slots
 
@@ -155,6 +276,7 @@ If no configuration is provided, the component uses Material Design Icons (inclu
 | `edit-icon`              | Custom edit icon                           |
 | `delete-icon`            | Custom delete icon                         |
 | `item.tfoot`             | Table footer content                       |
+| `selection-actions`      | Bar above the table, for bulk actions. Only rendered when `showSelect`. Receives `{ selected, count, clear }` |
 
 ## Peer Dependencies
 

package/dist/components/DataTable.vue.d.ts

@@ -1,11 +1,12 @@
-import type { TableHeader } from '../types';
+import type { TableHeader, DataTableColumn } from '../types';
 declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
         readonly onOnLoadData?: ((...args: any[]) => any) | undefined;
         readonly onEditItem?: ((...args: any[]) => any) | undefined;
         readonly onDeleteItem?: ((...args: any[]) => any) | undefined;
         readonly onViewItem?: ((...args: any[]) => any) | undefined;
-    } & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, never>, "onOnLoadData" | "onEditItem" | "onDeleteItem" | "onViewItem"> & {
+        readonly "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+    } & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, never>, "onOnLoadData" | "onEditItem" | "onDeleteItem" | "onViewItem" | "onUpdate:modelValue"> & {
         tableClass?: string;
         headers?: TableHeader[];
         items?: T[];
@@ -15,6 +16,9 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         itemsPerPage?: number;
         search?: string;
         showExpand?: boolean;
+        showSelect?: boolean;
+        selectStrategy?: "page" | "all" | "single";
+        modelValue?: (string | number)[];
         showEditButton?: boolean;
         showDeleteButton?: boolean;
         showViewButton?: boolean;
@@ -49,6 +53,23 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
             columns: any;
             item: any;
         }) => any) | undefined;
+    } & {
+        'column-chooser'?: (props: {
+            columns: DataTableColumn[];
+            hiddenCount: number;
+            label: string;
+            setVisible: (key: string, visible: boolean) => void;
+            toggleAll: () => void;
+            reset: () => void;
+            move: (key: string, step: -1 | 1) => void;
+            place: (key: string, targetKey: string) => void;
+        }) => any;
+    } & {
+        'selection-actions'?: (props: {
+            selected: (string | number)[];
+            count: number;
+            clear: () => void;
+        }) => any;
     } & {
         'before-actions'?: (props: {
             item: any;
@@ -66,7 +87,7 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
     } & {
         'item.tfoot'?: (props: {}) => any;
     };
-    emit: (event: "onLoadData" | "editItem" | "deleteItem" | "viewItem", ...args: any[]) => void;
+    emit: (event: "onLoadData" | "editItem" | "deleteItem" | "viewItem" | "update:modelValue", ...args: any[]) => void;
 }>) => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
     [key: string]: any;
 }> & {

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import DataTable from "./components/DataTable.vue";
 import { createDataTableConfig, DATA_TABLE_CONFIG_KEY } from "./config";
 export { DataTable };
 export { createDataTableConfig, DATA_TABLE_CONFIG_KEY };
-export type { DataTableConfig, DataTableIconConfig, TableHeader, SortItem, LoadDataParams, } from "./types";
+export type { DataTableColumn, DataTableConfig, DataTableIconConfig, DataTableText, DataTableTexts, TableHeader, SortItem, LoadDataParams, } from "./types";
 declare const _default: {
     install(app: App): void;
 };

package/dist/types.d.ts

@@ -15,10 +15,33 @@ export interface DataTableIconConfig {
     edit?: string | Component;
     delete?: string | Component;
 }
+/** A UI text, either fixed or read on every render (e.g. `() => i18n.global.t("key")`). */
+export type DataTableText = string | (() => string);
+export interface DataTableTexts {
+    columns?: DataTableText;
+    hiddenColumns?: (count: number) => string;
+    searchColumns?: DataTableText;
+    showAllColumns?: DataTableText;
+    hideAllColumns?: DataTableText;
+    resetColumns?: DataTableText;
+    moveColumn?: DataTableText;
+    scrollHint?: DataTableText;
+    scrollLeft?: DataTableText;
+    scrollRight?: DataTableText;
+}
+/** A column as listed by the column chooser, in its current order. */
+export interface DataTableColumn {
+    key: string;
+    title: string;
+    visible: boolean;
+}
 export interface DataTableConfig {
     icons?: DataTableIconConfig;
     iconProps?: Record<string, unknown>;
     tableClass?: string;
+    texts?: DataTableTexts;
+    /** Maps the localStorage key where column choices are saved (e.g. to add a tenant prefix). */
+    storageKey?: (key: string) => string;
 }
 export interface LoadDataParams {
     page: number;