v-datatable-plus 1.0.7 → 1.1.0

package/LICENSE.md

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) [2024] [Adnan Ahmed Ansari (ansaripro)]
-
-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.
+MIT License
+
+Copyright (c) [2024] [Adnan Ahmed Ansari (ansaripro)]
+
+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.

package/README.md

@@ -15,11 +15,186 @@
   </a>
 </p>
 
-VDatatablePlus is a an wrapper component for Vuetify VDataTable and VDataTableServer component, it gives you Header row filter functionlity like other advance data tables. It also utlilize VueDraggable Vue 3 library for columns drag n drop and show/hide functiionality.
-<br/>
-It also have other feature due to modification of based VDataTable/VDataTableServer components so you you can utilized them as per your need.  
-<br/><br/>
-This repository also expose a ResizeableSplitter component which is useful for split horizontal contents with or without user interaction.
+`v-datatable-plus` provides enhanced wrappers around Vuetify `VDataTable` and `VDataTableServer`.
+
+### Highlights
+
+- Header row filtering with typed filter modes (`FilterType`, `FilterMode`)
+- Column menu for show/hide, freeze/unfreeze, and reorder
+- Native column drag-and-drop (no external drag dependency)
+- Optional right panel layout with `ResizeableSplitter`
+- Works in both JavaScript and TypeScript projects
+
+### Requirements
+
+- Vue 3
+- Vuetify 3
+
+## TypeScript and JavaScript support
+
+This package supports both JavaScript and TypeScript projects.
+
+- JavaScript projects can use the package exactly as before.
+- TypeScript projects get declaration files from the package build output.
+- Typed constants are exported: `FilterType` and `FilterMode`.
+
+## Installation
+
+```bash
+npm install v-datatable-plus
+```
+
+## Latest Changes
+
+- Column drag is now built in.
+- `vuedraggable` is no longer a dependency.
+- `columnMenuDragChange` remains available and emits a `moved` payload with `element`, `oldIndex`, and `newIndex`.
+
+## Migration
+
+- Repository migration guide: [MIGRATION.md](MIGRATION.md)
+- Documentation migration page: [Migration](https://ansaripro.github.io/v-datatable-plus/migration)
+
+## Vuetify auto-import note
+
+If your app uses Vuetify auto-import/tree-shaking, components used inside external packages are not always detected automatically.
+
+Register the required Vuetify components in your `createVuetify` setup (for example: `VDataTable`, `VDataTableServer`, `VToolbar`, `VMenu`, `VList`, `VBtn`, `VCard`, `VIcon`, `VCheckboxBtn`, `VSelect`, `VPagination`, `VSpacer`, `VTextField`).
+
+Detailed setup examples are available in [documentation/getting-started.md](documentation/getting-started.md).
+
+## JavaScript usage
+
+```js
+import { createApp } from 'vue';
+import { createVuetify } from 'vuetify';
+import 'vuetify/styles';
+import 'v-datatable-plus/dist/v-datatable-plus.css';
+import VDatatablePlusPlugin from 'v-datatable-plus';
+
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(createVuetify());
+app.use(VDatatablePlusPlugin);
+app.mount('#app');
+```
+
+## TypeScript usage
+
+```ts
+import { createApp } from 'vue';
+import { createVuetify } from 'vuetify';
+import 'vuetify/styles';
+import 'v-datatable-plus/dist/v-datatable-plus.css';
+import VDatatablePlusPlugin, { FilterMode, FilterType } from 'v-datatable-plus';
+
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(createVuetify());
+app.use(VDatatablePlusPlugin);
+app.mount('#app');
+
+const filterType: (typeof FilterType)[keyof typeof FilterType] = FilterType.Contains;
+const filterMode: (typeof FilterMode)[keyof typeof FilterMode] = FilterMode.Types;
+```
+
+## Public type imports (TypeScript)
+
+```ts
+import type {
+  DataTableHeader,
+  GroupByItem,
+  ItemsPerPageOption,
+  RowItem,
+  RowClickEventPayload,
+  ColumnMenuEventPayload,
+  SelectedRowValue,
+} from 'v-datatable-plus';
+
+const headers: DataTableHeader[] = [
+  { key: 'name', title: 'Name', isShow: true, sortable: true },
+  { key: 'age', title: 'Age', isShow: true, sortable: true, align: 'end' },
+];
+
+const rows: RowItem[] = [
+  { id: 1, name: 'Alice', age: 32 },
+  { id: 2, name: 'Bob', age: 28 },
+];
+
+const groupBy: GroupByItem[] = [{ key: 'name', order: 'asc' }];
+const itemsPerPageOptions: ItemsPerPageOption[] = [{ value: 10, title: '10' }];
+
+let selectedRow: SelectedRowValue = null;
+
+function onRowClick(payload: RowClickEventPayload) {
+  selectedRow = payload.param?.item ?? null;
+}
+
+function onColumnMenuFixed(payload: ColumnMenuEventPayload) {
+  console.log(payload.element.key, payload.$event);
+}
+```
+
+## Typed wrapper component example
+
+```vue
+<script setup lang="ts">
+import {
+  VDatatablePlus,
+  type VDatatablePlusProps,
+  type VDatatablePlusEmits,
+  type RowClickEventPayload,
+} from 'v-datatable-plus';
+
+const props = defineProps<VDatatablePlusProps>();
+const emit = defineEmits<VDatatablePlusEmits>();
+
+function onClickRow(payload: RowClickEventPayload) {
+  emit('click:row', payload);
+}
+</script>
+
+<template>
+  <VDatatablePlus
+    v-bind="props"
+    @click:row="onClickRow"
+    @update:model-value="emit('update:modelValue', $event)"
+    @update:page="emit('update:page', $event)"
+  />
+</template>
+```
+
+## Typed server wrapper example
+
+```vue
+<script setup lang="ts">
+import {
+  VDatatableServerPlus,
+  type VDatatableServerPlusProps,
+  type VDatatableServerPlusEmits,
+  type RowClickEventPayload,
+} from 'v-datatable-plus';
+
+const props = defineProps<VDatatableServerPlusProps>();
+const emit = defineEmits<VDatatableServerPlusEmits>();
+
+function onClickRow(payload: RowClickEventPayload) {
+  emit('click:row', payload);
+}
+</script>
+
+<template>
+  <VDatatableServerPlus
+    v-bind="props"
+    @click:row="onClickRow"
+    @update:model-value="emit('update:modelValue', $event)"
+    @update:page="emit('update:page', $event)"
+    @update:items-per-page="emit('update:itemsPerPage', $event)"
+  />
+</template>
+```
 
 ## [Documentation](https://ansaripro.github.io/v-datatable-plus/)
 

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+import './style.css';
+import { FilterType, FilterMode } from './types/index';
+import VDatatablePlus from './components/VDatatablePlus.vue';
+import VDatatableServerPlus from './components/VDatatableServerPlus.vue';
+import ResizeableSplitter from './components/ResizeableSplitter.vue';
+import type { Plugin } from 'vue';
+declare const VDatatablePlusPlugin: Plugin;
+export default VDatatablePlusPlugin;
+export { VDatatablePlus, VDatatableServerPlus, ResizeableSplitter, FilterType, FilterMode };
+export type { FilterTypeValue, FilterModeValue, RowItem, SortDirection, GroupByItem, ItemsPerPageOption, SelectedRowValue, DataTableHeader, ColumnMenuEventPayload, RowClickEventPayload, VDatatablePlusProps, VDatatableServerPlusProps, VDatatablePlusEmits, VDatatableServerPlusEmits, } from './types/index';

package/dist/types/types/components.d.ts

@@ -0,0 +1,116 @@
+import type { ColumnMenuEventPayload, DataTableHeader, GroupByItem, ItemsPerPageOption, RowClickEventPayload, RowItem, SelectedRowValue } from './datatable';
+type AnyFn = (...args: any[]) => any;
+interface BaseDatatableProps {
+    hideTitleBar?: boolean;
+    hideColumnMenu?: boolean;
+    showRightPanel?: boolean;
+    hideFilterRow?: boolean;
+    hideFooter?: boolean;
+    selectOnRow?: boolean;
+    highlightRow?: boolean;
+    rightPanelFixed?: boolean;
+    rightPanelWidth?: number;
+    dragMenuHeight?: number;
+    tableHeight?: string | number;
+    selectedRow?: SelectedRowValue;
+    columnMenuZIndex?: string | number;
+    filterMenuZIndex?: string | number;
+    title?: string;
+    rowHighlightClass?: string;
+    headerTextSize?: string;
+    headerIconSize?: string;
+    color?: string;
+    itemValue?: string;
+    search?: string;
+    customFilter?: AnyFn;
+    valueComparator?: AnyFn;
+    returnObject?: boolean;
+    hideNoData?: boolean;
+    showExpand?: boolean;
+    showSelect?: boolean;
+    disableSort?: boolean;
+    expandOnClick?: boolean;
+    mobile?: boolean;
+    multiSort?: boolean;
+    mustSort?: boolean;
+    sticky?: boolean;
+    hover?: boolean;
+    expanded?: any[];
+    groupBy?: GroupByItem[];
+    modelValue?: any[];
+    theme?: string;
+    filterKeys?: string | string[];
+    customKeyFilter?: string | number | boolean | Record<string, any> | AnyFn;
+    customKeySort?: string | number | boolean | Record<string, any> | AnyFn;
+    mobileBreakpoint?: number | string;
+    itemSelectable?: string | Record<string, any> | AnyFn;
+    rowProps?: Record<string, any> | AnyFn;
+    cellProps?: Record<string, any> | AnyFn;
+    loading?: string | boolean;
+    sortBy?: Array<Record<string, any>>;
+    items?: RowItem[];
+    headers?: DataTableHeader[];
+    page?: string | number;
+    itemsPerPageOptions?: ItemsPerPageOption[];
+    noDataText?: string;
+    loadingText?: string;
+    filterMode?: string;
+    density?: string;
+    selectStrategy?: string;
+    sortAscIcon?: string;
+    sortDescIcon?: string;
+    firstIcon?: string;
+    lastIcon?: string;
+    nextIcon?: string;
+    prevIcon?: string;
+    dragMenuIcon?: string;
+    dragItemIcon?: string;
+    dragItemFreezeIcon?: string;
+    dragItemUnFreezeIcon?: string;
+    filterIcon?: string;
+    groupByIcon?: string;
+    groupSortAscIcon?: string;
+    groupSortDescIcon?: string;
+}
+export interface VDatatablePlusProps extends BaseDatatableProps {
+    itemsPerPage?: string | number;
+}
+export interface VDatatableServerPlusProps extends BaseDatatableProps {
+    itemsLength?: number;
+    itemsPerPage?: number;
+}
+export interface VDatatablePlusEmits {
+    (e: 'update:currentItems', value: any): void;
+    (e: 'update:expanded', value: any[]): void;
+    (e: 'update:groupBy', value: GroupByItem[]): void;
+    (e: 'update:itemsPerPage', value: string | number): void;
+    (e: 'update:modelValue', value: any[]): void;
+    (e: 'update:options', value: any): void;
+    (e: 'update:page', value: string | number): void;
+    (e: 'update:sortBy', value: Array<Record<string, any>>): void;
+    (e: 'update:headers', value: DataTableHeader[]): void;
+    (e: 'update:selectedRow', value: SelectedRowValue): void;
+    (e: 'click:row', value: RowClickEventPayload): void;
+    (e: 'columnMenuOpened', value: boolean): void;
+    (e: 'columnMenuDragChange', value: any): void;
+    (e: 'columnMenuChecked', value: ColumnMenuEventPayload): void;
+    (e: 'columnMenuFixed', value: ColumnMenuEventPayload): void;
+}
+export interface VDatatableServerPlusEmits {
+    (e: 'update:currentItems', value: any): void;
+    (e: 'update:expanded', value: any[]): void;
+    (e: 'update:groupBy', value: GroupByItem[]): void;
+    (e: 'update:itemsPerPage', value: number): void;
+    (e: 'update:modelValue', value: any[]): void;
+    (e: 'update:options', value: any): void;
+    (e: 'update:page', value: string | number): void;
+    (e: 'update:sortBy', value: Array<Record<string, any>>): void;
+    (e: 'update:headers', value: DataTableHeader[]): void;
+    (e: 'update:selectedRow', value: SelectedRowValue): void;
+    (e: 'click:row', value: RowClickEventPayload): void;
+    (e: 'columnMenuOpened', value: boolean): void;
+    (e: 'columnMenuDragChange', value: any): void;
+    (e: 'columnMenuChecked', value: ColumnMenuEventPayload): void;
+    (e: 'columnMenuFixed', value: ColumnMenuEventPayload): void;
+}
+export {};

package/dist/types/types/datatable.d.ts

@@ -0,0 +1,51 @@
+import type { FilterModeValue, FilterTypeValue } from './index';
+export type RowItem = Record<string, any>;
+export type SortDirection = 'asc' | 'desc' | string;
+export interface GroupByItem {
+    key: string;
+    order: SortDirection;
+}
+export interface ItemsPerPageOption {
+    value: string | number;
+    title: string;
+}
+export type SelectedRowValue = RowItem | string | number | boolean | null;
+export interface DataTableHeader {
+    key: string;
+    title?: string;
+    value?: any;
+    align?: any;
+    width?: number | string;
+    fixed?: boolean;
+    fixedOffset?: number;
+    lastFixed?: boolean;
+    rowSpan?: number;
+    colSpan?: number;
+    rowspan?: number;
+    colspan?: number;
+    children?: any[];
+    sortable?: boolean;
+    groupable?: boolean;
+    filterable?: boolean;
+    filterMode?: FilterModeValue | string;
+    filterType?: FilterTypeValue | string;
+    filterValue?: any;
+    allFilterValue?: any;
+    filterItems?: Array<{
+        title: string;
+        value: any;
+    }>;
+    isShow?: boolean;
+    isExclude?: boolean;
+    fixable?: boolean;
+    draggable?: boolean;
+    [key: string]: any;
+}
+export interface ColumnMenuEventPayload {
+    element: DataTableHeader;
+    $event: any;
+}
+export interface RowClickEventPayload {
+    $event: any;
+    param: any;
+}

package/dist/types/types/index.d.ts

@@ -0,0 +1,16 @@
+export declare const FilterType: {
+    readonly IsEqualTo: "eq";
+    readonly IsNotEqualTo: "neq";
+    readonly StartWith: "starts";
+    readonly Contains: "contains";
+    readonly NotContains: "notcontains";
+    readonly EndWith: "ends";
+};
+export declare const FilterMode: {
+    readonly Selection: "selection";
+    readonly Types: "types";
+};
+export type FilterTypeValue = (typeof FilterType)[keyof typeof FilterType];
+export type FilterModeValue = (typeof FilterMode)[keyof typeof FilterMode];
+export type { RowItem, SortDirection, GroupByItem, ItemsPerPageOption, SelectedRowValue, DataTableHeader, ColumnMenuEventPayload, RowClickEventPayload, } from './datatable';
+export type { VDatatablePlusProps, VDatatableServerPlusProps, VDatatablePlusEmits, VDatatableServerPlusEmits, } from './components';