@serhiitupilow/nuxt-table 0.1.4 → 0.1.5

package/README.md

@@ -109,6 +109,8 @@ import {
   type NuxtTableClassNames,
   type NuxtTableColumn,
   type NuxtTableColumnOrderChange,
+  type NuxtTableManualFilterChange,
+  type NuxtTableManualSortChange,
   type TableRow,
   type UseNuxtTableOptions,
   type ValueResolver,
@@ -134,14 +136,18 @@ import {
 
 ### Events
 
-| Event                 | Payload                      | Description                                     |
-| --------------------- | ---------------------------- | ----------------------------------------------- |
-| `column-order-change` | `NuxtTableColumnOrderChange` | Emitted after successful drag-and-drop reorder. |
+| Event                  | Payload                       | Description                                                                        |
+| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------- |
+| `column-order-change`  | `NuxtTableColumnOrderChange`  | Emitted after successful drag-and-drop reorder.                                    |
+| `manual-sort-change`   | `NuxtTableManualSortChange`   | Emitted when sorting is changed for a column with `sortFunction`.                  |
+| `manual-filter-change` | `NuxtTableManualFilterChange` | Emitted when filter value changes for a column with `filterFunction` / `filterFn`. |
 
 ### Behavior notes
 
 - Filtering is applied before sorting.
 - Sorting cycles by click: `asc -> desc -> off`.
+- If a column has `filterFunction` / `filterFn`, built-in filtering is disabled for that column and table emits `manual-filter-change`.
+- If a column has `sortFunction`, built-in sorting is disabled for that column and table emits `manual-sort-change`.
 - Column width has a minimum of `140px`.
 - Empty state text: `No rows match the current filters.`
 - Rendering is table-only (no built-in toolbar/summary controls).
@@ -161,12 +167,26 @@ interface NuxtTableColumn {
   sortDescComponent?: Component;
   sortDefaultComponent?: Component;
   sortKey?: ValueResolver;
+  sortFunction?: (
+    leftRow: TableRow,
+    rightRow: TableRow,
+    column: NuxtTableColumn,
+    tableRows: TableRow[],
+    direction: "asc" | "desc",
+  ) => number;
   filterKey?: ValueResolver;
   formatter?: (value: unknown, row: TableRow) => string;
+  filterFunction?: (
+    row: TableRow,
+    filterValue: unknown,
+    column: NuxtTableColumn,
+    tableRows: TableRow[],
+  ) => boolean;
   filterFn?: (
     row: TableRow,
     filterValue: unknown,
     column: NuxtTableColumn,
+    tableRows: TableRow[],
   ) => boolean;
   cellComponent?: Component;
   filterComponent?: Component;
@@ -179,10 +199,12 @@ interface NuxtTableColumn {
 
 - `key`: primary accessor path for display value. Supports dot notation through resolvers (for example: `user.profile.name`) when used by `sortKey`/`filterKey`.
 - `sortKey`: alternate accessor/function used for sorting.
+- `sortFunction`: enables manual sort mode for that column. Table emits `manual-sort-change` and does not sort rows automatically.
 - `sortAscComponent` / `sortDescComponent` / `sortDefaultComponent`: optional sort button content per state. If not provided, defaults are `Asc`, `Desc`, and `Sort`.
 - `filterKey`: alternate accessor/function used for default text filtering.
 - `formatter`: transforms display value for default body rendering (`<span>{{ value }}</span>`).
-- `filterFn`: custom row-level filter logic. If set, it overrides default string `includes` filtering for that column.
+- `filterFunction`: enables manual filter mode for that column. Table emits `manual-filter-change` and does not filter rows automatically.
+- `filterFn`: legacy alias for `filterFunction` (same manual behavior).
 - `cellComponent`: custom body renderer receives `row`, `column`, and `value`.
 - `filterComponent`: custom header filter renderer receives `modelValue` and `column`, and should emit `update:model-value`.
 
@@ -318,6 +340,245 @@ const columns: NuxtTableColumn[] = [
 
 If these components are not provided, the table automatically uses the default labels.
 
+### Detailed `manual-filter-change` and `manual-sort-change` flow
+
+When `filterFunction` / `sortFunction` is set, table switches that column to manual mode and emits `manual-filter-change` / `manual-sort-change`. You control final dataset in parent component.
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import type {
+  NuxtTableColumn,
+  NuxtTableManualFilterChange,
+  NuxtTableManualSortChange,
+} from "@serhiitupilow/nuxt-table/runtime";
+
+type TicketRow = {
+  id: number;
+  title: string;
+  priority: "low" | "medium" | "high" | "critical";
+  status: "todo" | "in_progress" | "done";
+  createdAt: string;
+};
+
+const allRows = ref<TicketRow[]>([
+  {
+    id: 1,
+    title: "Fix auth flow",
+    priority: "high",
+    status: "in_progress",
+    createdAt: "2026-02-18",
+  },
+  {
+    id: 2,
+    title: "Write docs",
+    priority: "low",
+    status: "done",
+    createdAt: "2026-02-10",
+  },
+  {
+    id: 3,
+    title: "Release v1",
+    priority: "critical",
+    status: "todo",
+    createdAt: "2026-02-20",
+  },
+]);
+
+const columns: NuxtTableColumn[] = [
+  { key: "id", label: "ID", sortable: true },
+  { key: "title", label: "Title", sortable: true, filterable: true },
+  {
+    key: "status",
+    label: "Status",
+    filterable: true,
+    filterFunction: () => true,
+  },
+  {
+    key: "priority",
+    label: "Priority",
+    sortable: true,
+    sortFunction: () => 0,
+  },
+];
+
+const manualStatusFilter = ref<string>("");
+const manualSort = ref<{ key: string; direction: "asc" | "desc" | null }>({
+  key: "",
+  direction: null,
+});
+
+const rows = computed(() => {
+  const statusFiltered = allRows.value.filter((row) => {
+    if (!manualStatusFilter.value) {
+      return true;
+    }
+
+    return row.status === manualStatusFilter.value;
+  });
+
+  if (manualSort.value.key !== "priority" || !manualSort.value.direction) {
+    return statusFiltered;
+  }
+
+  const rank: Record<TicketRow["priority"], number> = {
+    low: 0,
+    medium: 1,
+    high: 2,
+    critical: 3,
+  };
+
+  const directionMultiplier = manualSort.value.direction === "asc" ? 1 : -1;
+
+  return [...statusFiltered].sort((left, right) => {
+    return (rank[left.priority] - rank[right.priority]) * directionMultiplier;
+  });
+});
+
+function onManualFilterChange(payload: NuxtTableManualFilterChange) {
+  if (payload.columnKey !== "status") {
+    return;
+  }
+
+  manualStatusFilter.value = String(payload.value ?? "").trim();
+}
+
+function onManualSortChange(payload: NuxtTableManualSortChange) {
+  manualSort.value = {
+    key: payload.columnKey,
+    direction: payload.direction,
+  };
+}
+</script>
+
+<template>
+  <NuxtTable
+    :columns="columns"
+    :rows="rows"
+    @manual-filter-change="onManualFilterChange"
+    @manual-sort-change="onManualSortChange"
+  />
+</template>
+```
+
+Notes:
+
+- In manual mode, the table does not transform rows for that column; you pass already transformed `rows` from outside.
+- Use payload `columnKey`, `value`, `direction`, `rows`, and `filters` from events to build server/client-side query logic.
+- `filterFn` remains supported as a legacy alias, but `filterFunction` is preferred.
+
+### Server-side `manual-filter-change` / `manual-sort-change` example
+
+Use manual events to request data from backend and pass ready rows back to table.
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import type {
+  NuxtTableColumn,
+  NuxtTableManualFilterChange,
+  NuxtTableManualSortChange,
+} from "@serhiitupilow/nuxt-table/runtime";
+
+type UserRow = {
+  id: number;
+  name: string;
+  status: "active" | "paused";
+  createdAt: string;
+};
+
+const rows = ref<UserRow[]>([]);
+const loading = ref(false);
+
+const query = ref<{
+  page: number;
+  pageSize: number;
+  status: string;
+  sortKey: string;
+  sortDirection: "asc" | "desc" | "";
+}>({
+  page: 1,
+  pageSize: 20,
+  status: "",
+  sortKey: "",
+  sortDirection: "",
+});
+
+const columns: NuxtTableColumn[] = [
+  { key: "id", label: "ID", sortable: true },
+  { key: "name", label: "Name", sortable: true, filterable: true },
+  {
+    key: "status",
+    label: "Status",
+    filterable: true,
+    filterFunction: () => true,
+  },
+  {
+    key: "createdAt",
+    label: "Created",
+    sortable: true,
+    sortFunction: () => 0,
+  },
+];
+
+async function fetchRows() {
+  loading.value = true;
+
+  try {
+    const data = await $fetch<UserRow[]>("/api/users", {
+      query: {
+        page: query.value.page,
+        pageSize: query.value.pageSize,
+        status: query.value.status,
+        sortKey: query.value.sortKey,
+        sortDirection: query.value.sortDirection,
+      },
+    });
+
+    rows.value = data;
+  } finally {
+    loading.value = false;
+  }
+}
+
+function onManualFilterChange(payload: NuxtTableManualFilterChange) {
+  if (payload.columnKey === "status") {
+    query.value.status = String(payload.value ?? "").trim();
+    query.value.page = 1;
+  }
+
+  fetchRows();
+}
+
+function onManualSortChange(payload: NuxtTableManualSortChange) {
+  query.value.sortKey = payload.columnKey;
+  query.value.sortDirection = payload.direction ?? "";
+  query.value.page = 1;
+
+  fetchRows();
+}
+
+await fetchRows();
+</script>
+
+<template>
+  <NuxtTable
+    :columns="columns"
+    :rows="rows"
+    @manual-filter-change="onManualFilterChange"
+    @manual-sort-change="onManualSortChange"
+  />
+
+  <p v-if="loading">Loading...</p>
+</template>
+```
+
+What happens here:
+
+- `filterFunction` and `sortFunction` switch corresponding columns to manual mode.
+- Table emits `manual-filter-change` / `manual-sort-change` instead of transforming `rows` internally.
+- Parent updates query params, calls API, and passes backend result as new `rows`.
+
 ### Custom filter component
 
 ```vue

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@serhiitupilow/nuxt-table",
   "configKey": "nuxtTable",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/components/NuxtTable.d.vue.ts

@@ -1,4 +1,4 @@
-import type { NuxtTableClassNames, NuxtTableColumn, NuxtTableColumnOrderChange, TableRow } from "../types/table.js";
+import type { NuxtTableClassNames, NuxtTableColumn, NuxtTableColumnOrderChange, NuxtTableManualFilterChange, NuxtTableManualSortChange, TableRow } from "../types/table.js";
 type __VLS_Props = {
     columns: NuxtTableColumn[];
     rows: TableRow[];
@@ -13,8 +13,12 @@ type __VLS_Props = {
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     columnOrderChange: (payload: NuxtTableColumnOrderChange) => any;
+    manualSortChange: (payload: NuxtTableManualSortChange) => any;
+    manualFilterChange: (payload: NuxtTableManualFilterChange) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onColumnOrderChange?: ((payload: NuxtTableColumnOrderChange) => any) | undefined;
+    onManualSortChange?: ((payload: NuxtTableManualSortChange) => any) | undefined;
+    onManualFilterChange?: ((payload: NuxtTableManualFilterChange) => any) | undefined;
 }>, {
     storageKey: string;
     rowKey: string | ((row: TableRow, index: number) => string | number);

package/dist/runtime/components/NuxtTable.vue

@@ -13,7 +13,7 @@ const props = defineProps({
   enableColumnResize: { type: Boolean, required: false, default: true },
   classNames: { type: Object, required: false }
 });
-const emit = defineEmits(["columnOrderChange"]);
+const emit = defineEmits(["columnOrderChange", "manualSortChange", "manualFilterChange"]);
 const defaultClassNames = {
   root: "nuxt-table",
   toolbar: "nuxt-table__toolbar",
@@ -73,6 +73,12 @@ const {
   enableColumnDnd: toRef(props, "enableColumnDnd"),
   onColumnOrderChange: (payload) => {
     emit("columnOrderChange", payload);
+  },
+  onManualSortChange: (payload) => {
+    emit("manualSortChange", payload);
+  },
+  onManualFilterChange: (payload) => {
+    emit("manualFilterChange", payload);
   }
 });
 const displayedColumns = computed(() => {

package/dist/runtime/components/NuxtTable.vue.d.ts

@@ -1,4 +1,4 @@
-import type { NuxtTableClassNames, NuxtTableColumn, NuxtTableColumnOrderChange, TableRow } from "../types/table.js";
+import type { NuxtTableClassNames, NuxtTableColumn, NuxtTableColumnOrderChange, NuxtTableManualFilterChange, NuxtTableManualSortChange, TableRow } from "../types/table.js";
 type __VLS_Props = {
     columns: NuxtTableColumn[];
     rows: TableRow[];
@@ -13,8 +13,12 @@ type __VLS_Props = {
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     columnOrderChange: (payload: NuxtTableColumnOrderChange) => any;
+    manualSortChange: (payload: NuxtTableManualSortChange) => any;
+    manualFilterChange: (payload: NuxtTableManualFilterChange) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onColumnOrderChange?: ((payload: NuxtTableColumnOrderChange) => any) | undefined;
+    onManualSortChange?: ((payload: NuxtTableManualSortChange) => any) | undefined;
+    onManualFilterChange?: ((payload: NuxtTableManualFilterChange) => any) | undefined;
 }>, {
     storageKey: string;
     rowKey: string | ((row: TableRow, index: number) => string | number);

package/dist/runtime/composables/useNuxtTable.js

@@ -41,8 +41,9 @@ export function useNuxtTable(options) {
         if (!isFilterActive(filterValue)) {
           return true;
         }
-        if (column.filterFn) {
-          return column.filterFn(row, filterValue, column);
+        const customFilterFunction = column.filterFunction ?? column.filterFn;
+        if (customFilterFunction) {
+          return true;
         }
         const candidate = resolveColumnValue(
           row,
@@ -62,8 +63,13 @@ export function useNuxtTable(options) {
     if (!activeColumn) {
       return filteredRows.value;
     }
-    const directionMultiplier = sortState.value.direction === "asc" ? 1 : -1;
+    const sortDirection = sortState.value.direction;
+    const directionMultiplier = sortDirection === "asc" ? 1 : -1;
     const accessor = activeColumn.sortKey ?? activeColumn.key;
+    const customSortFunction = activeColumn.sortFunction;
+    if (customSortFunction) {
+      return filteredRows.value;
+    }
     return [...filteredRows.value].sort((leftRow, rightRow) => {
       const leftValue = resolveColumnValue(leftRow, accessor);
       const rightValue = resolveColumnValue(rightRow, accessor);
@@ -212,16 +218,58 @@ export function useNuxtTable(options) {
     }
     if (!sortState.value || sortState.value.key !== column.key) {
       sortState.value = { key: column.key, direction: "asc" };
+      if (column.sortFunction) {
+        options.onManualSortChange?.({
+          columnKey: column.key,
+          direction: "asc",
+          column,
+          rows: [...options.rows.value],
+          filters: { ...filters.value }
+        });
+      }
       return;
     }
     if (sortState.value.direction === "asc") {
       sortState.value = { key: column.key, direction: "desc" };
+      if (column.sortFunction) {
+        options.onManualSortChange?.({
+          columnKey: column.key,
+          direction: "desc",
+          column,
+          rows: [...options.rows.value],
+          filters: { ...filters.value }
+        });
+      }
       return;
     }
     sortState.value = null;
+    if (column.sortFunction) {
+      options.onManualSortChange?.({
+        columnKey: column.key,
+        direction: null,
+        column,
+        rows: [...options.rows.value],
+        filters: { ...filters.value }
+      });
+    }
   }
   function setFilter(columnKey, value) {
     filters.value[columnKey] = value;
+    const column = columnsByKey.value.get(columnKey);
+    if (!column) {
+      return;
+    }
+    const customFilterFunction = column.filterFunction ?? column.filterFn;
+    if (!customFilterFunction) {
+      return;
+    }
+    options.onManualFilterChange?.({
+      columnKey,
+      value,
+      column,
+      rows: [...options.rows.value],
+      filters: { ...filters.value }
+    });
   }
   function toggleColumn(columnKey) {
     if (enabledColumnKeys.value.includes(columnKey)) {

package/dist/runtime/index.d.ts

@@ -1,2 +1,2 @@
-export { useNuxtTable } from './composables/useNuxtTable.js';
-export type { NuxtTableClassNames, NuxtTableColumn, NuxtTableColumnOrderChange, TableRow, UseNuxtTableOptions, ValueResolver, } from './types/table.js';
+export { useNuxtTable } from "./composables/useNuxtTable.js";
+export type { NuxtTableClassNames, NuxtTableColumn, NuxtTableColumnOrderChange, NuxtTableManualFilterChange, NuxtTableManualSortChange, TableRow, UseNuxtTableOptions, ValueResolver, } from "./types/table.js";

package/dist/runtime/types/table.d.ts

@@ -10,9 +10,11 @@ export interface NuxtTableColumn {
     sortDescComponent?: Component;
     sortDefaultComponent?: Component;
     sortKey?: ValueResolver;
+    sortFunction?: (leftRow: TableRow, rightRow: TableRow, column: NuxtTableColumn, tableRows: TableRow[], direction: "asc" | "desc") => number;
     filterKey?: ValueResolver;
     formatter?: (value: unknown, row: TableRow) => string;
-    filterFn?: (row: TableRow, filterValue: unknown, column: NuxtTableColumn) => boolean;
+    filterFunction?: (row: TableRow, filterValue: unknown, column: NuxtTableColumn, tableRows: TableRow[]) => boolean;
+    filterFn?: (row: TableRow, filterValue: unknown, column: NuxtTableColumn, tableRows: TableRow[]) => boolean;
     cellComponent?: Component;
     filterComponent?: Component;
     headerClassName?: string;
@@ -24,6 +26,20 @@ export interface NuxtTableColumnOrderChange {
     fromIndex: number;
     toIndex: number;
 }
+export interface NuxtTableManualSortChange {
+    columnKey: string;
+    direction: "asc" | "desc" | null;
+    column: NuxtTableColumn;
+    rows: TableRow[];
+    filters: Record<string, unknown>;
+}
+export interface NuxtTableManualFilterChange {
+    columnKey: string;
+    value: unknown;
+    column: NuxtTableColumn;
+    rows: TableRow[];
+    filters: Record<string, unknown>;
+}
 export interface NuxtTableClassNames {
     root: string;
     toolbar: string;
@@ -56,4 +72,6 @@ export interface UseNuxtTableOptions {
     rowKey: Ref<string | ((row: TableRow, index: number) => string | number)>;
     enableColumnDnd: Ref<boolean>;
     onColumnOrderChange?: (payload: NuxtTableColumnOrderChange) => void;
+    onManualSortChange?: (payload: NuxtTableManualSortChange) => void;
+    onManualFilterChange?: (payload: NuxtTableManualFilterChange) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serhiitupilow/nuxt-table",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Nuxt module with a functional table component (sorting, filtering, column visibility, resize, optional DnD)",
   "type": "module",
   "license": "MIT",