@serhiitupilow/nuxt-table 0.1.4 → 0.1.6

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 sort state changes and `@manual-sort-change` listener is provided.     |
+| `manual-filter-change` | `NuxtTableManualFilterChange` | Emitted when filter value changes and `@manual-filter-change` listener is provided. |
 
 ### Behavior notes
 
 - Filtering is applied before sorting.
 - Sorting cycles by click: `asc -> desc -> off`.
+- If `@manual-filter-change` is provided, built-in filtering is disabled.
+- If `@manual-sort-change` is provided, built-in sorting is disabled.
 - 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).
@@ -163,11 +169,6 @@ interface NuxtTableColumn {
   sortKey?: ValueResolver;
   filterKey?: ValueResolver;
   formatter?: (value: unknown, row: TableRow) => string;
-  filterFn?: (
-    row: TableRow,
-    filterValue: unknown,
-    column: NuxtTableColumn,
-  ) => boolean;
   cellComponent?: Component;
   filterComponent?: Component;
   headerClassName?: string;
@@ -182,7 +183,6 @@ interface NuxtTableColumn {
 - `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.
 - `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 +318,224 @@ 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 `@manual-filter-change` / `@manual-sort-change` listeners are passed, table switches to manual mode and emits these events. 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 },
+  { key: "priority", label: "Priority", sortable: true },
+];
+
+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 internally; you pass already transformed `rows` from outside.
+- Use payload `columnKey`, `value`, `direction`, `rows`, and `filters` from events to build server/client-side query logic.
+
+### 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 },
+  { key: "createdAt", label: "Created", sortable: true },
+];
+
+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:
+
+- Passing `@manual-filter-change` and `@manual-sort-change` switches the table 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.6",
   "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

@@ -1,5 +1,5 @@
 <script setup>
-import { computed, toRef } from "vue";
+import { computed, toRef, useAttrs } from "vue";
 import { useNuxtTable } from "../composables/useNuxtTable";
 const props = defineProps({
   columns: { type: Array, required: true },
@@ -13,7 +13,14 @@ 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 attrs = useAttrs();
+const hasManualSortChangeListener = computed(() => {
+  return Boolean(attrs.onManualSortChange);
+});
+const hasManualFilterChangeListener = computed(() => {
+  return Boolean(attrs.onManualFilterChange);
+});
 const defaultClassNames = {
   root: "nuxt-table",
   toolbar: "nuxt-table__toolbar",
@@ -73,7 +80,13 @@ const {
   enableColumnDnd: toRef(props, "enableColumnDnd"),
   onColumnOrderChange: (payload) => {
     emit("columnOrderChange", payload);
-  }
+  },
+  onManualSortChange: hasManualSortChangeListener.value ? (payload) => {
+    emit("manualSortChange", payload);
+  } : void 0,
+  onManualFilterChange: hasManualFilterChangeListener.value ? (payload) => {
+    emit("manualFilterChange", payload);
+  } : void 0
 });
 const displayedColumns = computed(() => {
   if (!props.enabledColumns) {

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

@@ -20,6 +20,10 @@ export function useNuxtTable(options) {
   const headerElements = ref({});
   const columnWidths = ref({});
   const activeResize = ref(null);
+  const isManualSortMode = computed(() => Boolean(options.onManualSortChange));
+  const isManualFilterMode = computed(
+    () => Boolean(options.onManualFilterChange)
+  );
   const availableColumnKeys = computed(
     () => options.columns.value.map((column) => column.key)
   );
@@ -41,8 +45,8 @@ export function useNuxtTable(options) {
         if (!isFilterActive(filterValue)) {
           return true;
         }
-        if (column.filterFn) {
-          return column.filterFn(row, filterValue, column);
+        if (isManualFilterMode.value) {
+          return true;
         }
         const candidate = resolveColumnValue(
           row,
@@ -62,8 +66,12 @@ 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;
+    if (isManualSortMode.value) {
+      return filteredRows.value;
+    }
     return [...filteredRows.value].sort((leftRow, rightRow) => {
       const leftValue = resolveColumnValue(leftRow, accessor);
       const rightValue = resolveColumnValue(rightRow, accessor);
@@ -212,16 +220,57 @@ export function useNuxtTable(options) {
     }
     if (!sortState.value || sortState.value.key !== column.key) {
       sortState.value = { key: column.key, direction: "asc" };
+      if (isManualSortMode.value) {
+        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 (isManualSortMode.value) {
+        options.onManualSortChange?.({
+          columnKey: column.key,
+          direction: "desc",
+          column,
+          rows: [...options.rows.value],
+          filters: { ...filters.value }
+        });
+      }
       return;
     }
     sortState.value = null;
+    if (isManualSortMode.value) {
+      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;
+    }
+    if (!isManualFilterMode.value) {
+      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

@@ -12,7 +12,6 @@ export interface NuxtTableColumn {
     sortKey?: ValueResolver;
     filterKey?: ValueResolver;
     formatter?: (value: unknown, row: TableRow) => string;
-    filterFn?: (row: TableRow, filterValue: unknown, column: NuxtTableColumn) => boolean;
     cellComponent?: Component;
     filterComponent?: Component;
     headerClassName?: string;
@@ -24,6 +23,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 +69,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.6",
   "description": "Nuxt module with a functional table component (sorting, filtering, column visibility, resize, optional DnD)",
   "type": "module",
   "license": "MIT",