@saulpaulus17/vue-datatables-flex 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 saul paulus (Ixspx)
+
+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

@@ -0,0 +1,209 @@
+# @saulpaulus17/vue-datatables-flex
+
+A high-performance, responsive DataTable component for Vue 3 and Nuxt 3/4.
+
+[![npm version](https://img.shields.io/npm/v/@saulpaulus17/vue-datatables-flex.svg?style=flat-square)](https://www.npmjs.com/package/@saulpaulus17/vue-datatables-flex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Vue Version](https://img.shields.io/badge/Vue-3.x-42b883?style=flat-square&logo=vue.js)](https://vuejs.org/)
+[![Nuxt Version](https://img.shields.io/badge/Nuxt-3.x%20|%204.x-00dc82?style=flat-square&logo=nuxt.js)](https://nuxt.com/)
+
+---
+
+## Features
+
+- Optimized performance using DataTables
+- Clean UI with Bootstrap 5 styling
+- Fully responsive layout
+- Nuxt 3 & 4 module support
+- TypeScript support
+- SSR-friendly rendering
+- Indonesian locale ready
+
+---
+
+## 🚀 Installation
+
+Install the package:
+
+```bash
+npm install @saulpaulus17/vue-datatables-flex
+```
+
+### Required Peer Dependencies
+
+Ensure your project has the following essentials installed:
+
+```bash
+npm install vue bootstrap datatables.net-bs5
+```
+
+---
+
+## 📦 Usage in Vue 3
+
+### Global Registration
+
+Recommended for large applications using the component across multiple pages.
+
+```ts
+// main.ts
+import { createApp } from "vue";
+import { VueDatatablesFlex } from "@saulpaulus17/vue-datatables-flex";
+import App from "./App.vue";
+
+// Import Required CSS
+import "bootstrap/dist/css/bootstrap.min.css";
+import "datatables.net-bs5/css/dataTables.bootstrap5.min.css";
+
+const app = createApp(App);
+app.use(VueDatatablesFlex);
+app.mount("#app");
+```
+
+### Basic Usage
+
+```vue
+<template>
+  <MainDataTable
+    :data="userRows"
+    :columns="userColumns"
+    scroll-y="500px"
+    @ready="onReady"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import type { Column } from "@saulpaulus17/vue-datatables-flex";
+
+const userColumns: Column[] = [
+  { data: "id", title: "ID" },
+  { data: "name", title: "Full Name" },
+  { data: "email", title: "Email Address" },
+];
+
+const userRows = ref([
+  { id: 1, name: "Ahmad", email: "ahmad@example.com" },
+  { id: 2, name: "Budi", email: "budi@example.com" },
+]);
+
+const onReady = (dt: any) => console.log("Table instance:", dt);
+</script>
+```
+
+---
+
+## 🟢 Usage in Nuxt 3 & 4
+
+The simplest way is to use the provided Nuxt module. It handles everything including **Universal Rendering (SSR)**.
+
+### 1. Add to Nuxt Config
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@saulpaulus17/vue-datatables-flex/nuxt"],
+
+  // Optional: Module Configuration
+  vueDatatablesFlex: {
+    componentName: "MainDataTable", // Use a custom component name
+    addCss: true, // Automatically includes DataTables Bootstrap 5 CSS (default: true)
+  },
+
+  // You still need to include Bootstrap 5 CSS
+  css: ["bootstrap/dist/css/bootstrap.min.css"],
+});
+```
+
+### 2. Implementation
+
+```vue
+<!-- pages/users.vue -->
+<script setup lang="ts">
+const columns = [{ data: "name", title: "Name" }];
+const { data: users } = await useFetch("/api/users");
+</script>
+
+<template>
+  <!-- No import needed! Component is auto-registered -->
+  <MainDataTable :data="users" :columns="columns" />
+</template>
+```
+
+> [!TIP]
+> **Universal Rendering Support:**
+> Version 0.1.4+ is fully SSR-aware. While the interactive DataTable initializes on the client, the component renders a semantic HTML table on the server. This ensures your data is **visible to search engines** and avoids Cumulative Layout Shift (CLS).
+
+---
+
+## 🛠 API Reference
+
+### Props
+
+| Property     | Type               | Default  | Description                                          |
+| :----------- | :----------------- | :------- | :--------------------------------------------------- |
+| `data`       | `unknown[]`        | `[]`     | The data array to display (Alias: `dataTableProps`). |
+| `columns`    | `Column[]`         | `[]`     | Column definitions (Alias: `columnsProps`).          |
+| `options`    | `DataTableOptions` | `{}`     | Advanced DataTables configuration overrides.         |
+| `loading`    | `boolean`          | `false`  | Shows a beautiful animated loading overlay.          |
+| `responsive` | `boolean`          | `false`  | Enables DataTables Responsive extension.             |
+| `scrollY`    | `string \| number` | `'65vh'` | Sets the vertical scroll height.                     |
+| `tableClass` | `string`           | `''`     | Custom CSS class for the `<table>` element.          |
+
+### Events
+
+| Event     | Payload           | Description                                               |
+| :-------- | :---------------- | :-------------------------------------------------------- |
+| `@ready`  | `(instance: Api)` | Fired when initialization is complete.                    |
+| `@draw`   | `(settings: any)` | Fired whenever the table is redrawn (sort, filter, page). |
+| `@select` | `(items, type)`   | Fired when rows are selected (requires `select: true`).   |
+| `@error`  | `(err: Error)`    | Fired if initialization fails.                            |
+
+### Exposed Methods (Template Ref)
+
+Access these by adding a `ref` to your component:
+
+```ts
+const table = ref<InstanceType<typeof MainDataTable>>();
+
+// Methods
+table.value?.getInstance(); // Get raw DataTables API instance
+table.value?.reload(); // Reload AJAX data (if using server-side)
+table.value?.adjustColumns(); // recalculate column widths
+```
+
+---
+
+## 🎨 Customizing Columns
+
+```ts
+const columns: Column[] = [
+  {
+    data: "status",
+    title: "Status",
+    className: "text-center",
+    render: (data) => {
+      const color = data === "Active" ? "success" : "secondary";
+      return `<span class="badge bg-${color}">${data}</span>`;
+    },
+  },
+];
+```
+
+---
+
+## 🙋 Troubleshooting
+
+**"JQuery is not defined"**
+Ensure you are importing the Bootstrap integration correctly in your entry point: `import 'datatables.net-bs5';`.
+
+**CSS Alignment Issues**
+Ensure you've imported BOTH the Bootstrap 5 core CSS and the DataTables Bootstrap 5 styling in the correct order.
+
+---
+
+## 📄 License
+
+This package is open-sourced software licensed under the [MIT License](LICENSE).
+
+Built with ❤️ for the Vue ecosystem.

package/dist/nuxt.cjs.js

@@ -0,0 +1,30 @@
+"use strict";
+const kit = require("@nuxt/kit");
+var _documentCurrentScript = typeof document !== "undefined" ? document.currentScript : null;
+const nuxt = kit.defineNuxtModule({
+  meta: {
+    name: "@saulpaulus17/vue-datatables-flex",
+    configKey: "vueDatatablesFlex",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    componentName: "MainDataTable",
+    addCss: true
+  },
+  setup(options, nuxt2) {
+    const resolver = kit.createResolver(typeof document === "undefined" ? require("url").pathToFileURL(__filename).href : _documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === "SCRIPT" && _documentCurrentScript.src || new URL("nuxt.cjs.js", document.baseURI).href);
+    kit.addComponent({
+      name: options.componentName || "MainDataTable",
+      // Point langsung ke file .vue di folder runtime
+      filePath: resolver.resolve("./runtime/components/MainDataTable.vue")
+    });
+    if (options.addCss) {
+      nuxt2.options.css.push("datatables.net-bs5/css/dataTables.bootstrap5.min.css");
+    }
+    nuxt2.options.build.transpile.push("@saulpaulus17/vue-datatables-flex");
+  }
+});
+module.exports = nuxt;
+//# sourceMappingURL=nuxt.cjs.js.map

package/dist/nuxt.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nuxt.cjs.js","sources":["../src/nuxt.ts"],"sourcesContent":["import { defineNuxtModule, addComponent, createResolver } from '@nuxt/kit'\n\nexport interface ModuleOptions {\n  /** Nama komponen global yang didaftarkan (default: \"MainDataTable\") */\n  componentName?: string;\n  /** Auto-import CSS Bootstrap DataTables */\n  addCss?: boolean;\n}\n\nexport default defineNuxtModule<ModuleOptions>({\n  meta: {\n    name: '@saulpaulus17/vue-datatables-flex',\n    configKey: 'vueDatatablesFlex',\n    compatibility: {\n      nuxt: '>=3.0.0'\n    }\n  },\n  defaults: {\n    componentName: 'MainDataTable',\n    addCss: true\n  },\n  setup(options: ModuleOptions, nuxt: any) {\n    const resolver = createResolver(import.meta.url)\n\n    // Daftarkan komponen secara global (Default: MainDataTable)\n    addComponent({\n      name: options.componentName || 'MainDataTable',\n      // Point langsung ke file .vue di folder runtime\n      filePath: resolver.resolve('./runtime/components/MainDataTable.vue'),\n    })\n\n    // Tambah CSS jika diminta\n    if (options.addCss) {\n      nuxt.options.css.push('datatables.net-bs5/css/dataTables.bootstrap5.min.css')\n    }\n\n    // Pastikan library di-transpile oleh Nuxt\n    nuxt.options.build.transpile.push('@saulpaulus17/vue-datatables-flex')\n  }\n})\n"],"names":["defineNuxtModule","nuxt","createResolver","addComponent"],"mappings":";;;AASA,MAAA,OAAeA,qBAAgC;AAAA,EAC7C,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,WAAW;AAAA,IACX,eAAe;AAAA,MACb,MAAM;AAAA,IAAA;AAAA,EACR;AAAA,EAEF,UAAU;AAAA,IACR,eAAe;AAAA,IACf,QAAQ;AAAA,EAAA;AAAA,EAEV,MAAM,SAAwBC,OAAW;AACvC,UAAM,WAAWC,IAAAA,mQAA8B;AAG/CC,qBAAa;AAAA,MACX,MAAM,QAAQ,iBAAiB;AAAA;AAAA,MAE/B,UAAU,SAAS,QAAQ,wCAAwC;AAAA,IAAA,CACpE;AAGD,QAAI,QAAQ,QAAQ;AAClB,MAAAF,MAAK,QAAQ,IAAI,KAAK,sDAAsD;AAAA,IAC9E;AAGA,IAAAA,MAAK,QAAQ,MAAM,UAAU,KAAK,mCAAmC;AAAA,EACvE;AACF,CAAC;;"}

package/dist/nuxt.es.js

@@ -0,0 +1,30 @@
+import { defineNuxtModule, createResolver, addComponent } from "@nuxt/kit";
+const nuxt = defineNuxtModule({
+  meta: {
+    name: "@saulpaulus17/vue-datatables-flex",
+    configKey: "vueDatatablesFlex",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    componentName: "MainDataTable",
+    addCss: true
+  },
+  setup(options, nuxt2) {
+    const resolver = createResolver(import.meta.url);
+    addComponent({
+      name: options.componentName || "MainDataTable",
+      // Point langsung ke file .vue di folder runtime
+      filePath: resolver.resolve("./runtime/components/MainDataTable.vue")
+    });
+    if (options.addCss) {
+      nuxt2.options.css.push("datatables.net-bs5/css/dataTables.bootstrap5.min.css");
+    }
+    nuxt2.options.build.transpile.push("@saulpaulus17/vue-datatables-flex");
+  }
+});
+export {
+  nuxt as default
+};
+//# sourceMappingURL=nuxt.es.js.map

package/dist/nuxt.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nuxt.es.js","sources":["../src/nuxt.ts"],"sourcesContent":["import { defineNuxtModule, addComponent, createResolver } from '@nuxt/kit'\n\nexport interface ModuleOptions {\n  /** Nama komponen global yang didaftarkan (default: \"MainDataTable\") */\n  componentName?: string;\n  /** Auto-import CSS Bootstrap DataTables */\n  addCss?: boolean;\n}\n\nexport default defineNuxtModule<ModuleOptions>({\n  meta: {\n    name: '@saulpaulus17/vue-datatables-flex',\n    configKey: 'vueDatatablesFlex',\n    compatibility: {\n      nuxt: '>=3.0.0'\n    }\n  },\n  defaults: {\n    componentName: 'MainDataTable',\n    addCss: true\n  },\n  setup(options: ModuleOptions, nuxt: any) {\n    const resolver = createResolver(import.meta.url)\n\n    // Daftarkan komponen secara global (Default: MainDataTable)\n    addComponent({\n      name: options.componentName || 'MainDataTable',\n      // Point langsung ke file .vue di folder runtime\n      filePath: resolver.resolve('./runtime/components/MainDataTable.vue'),\n    })\n\n    // Tambah CSS jika diminta\n    if (options.addCss) {\n      nuxt.options.css.push('datatables.net-bs5/css/dataTables.bootstrap5.min.css')\n    }\n\n    // Pastikan library di-transpile oleh Nuxt\n    nuxt.options.build.transpile.push('@saulpaulus17/vue-datatables-flex')\n  }\n})\n"],"names":["nuxt"],"mappings":";AASA,MAAA,OAAe,iBAAgC;AAAA,EAC7C,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,WAAW;AAAA,IACX,eAAe;AAAA,MACb,MAAM;AAAA,IAAA;AAAA,EACR;AAAA,EAEF,UAAU;AAAA,IACR,eAAe;AAAA,IACf,QAAQ;AAAA,EAAA;AAAA,EAEV,MAAM,SAAwBA,OAAW;AACvC,UAAM,WAAW,eAAe,YAAY,GAAG;AAG/C,iBAAa;AAAA,MACX,MAAM,QAAQ,iBAAiB;AAAA;AAAA,MAE/B,UAAU,SAAS,QAAQ,wCAAwC;AAAA,IAAA,CACpE;AAGD,QAAI,QAAQ,QAAQ;AAClB,MAAAA,MAAK,QAAQ,IAAI,KAAK,sDAAsD;AAAA,IAC9E;AAGA,IAAAA,MAAK,QAAQ,MAAM,UAAU,KAAK,mCAAmC;AAAA,EACvE;AACF,CAAC;"}

package/dist/runtime/components/MainDataTable.vue

@@ -0,0 +1,341 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
+import DataTableSource from "datatables.net-vue3";
+import DataTablesLib from "datatables.net-bs5";
+import "datatables.net-responsive-bs5";
+import "datatables.net-select-bs5";
+
+import type { Api } from "datatables.net";
+import type { Column, DataTableOptions } from "../types/index";
+import { defaultOptions } from "../types/index";
+
+// Datatables.net component: casting to any avoids leaky types (TS4058 / JQueryDataTables)
+const DataTableComponent = DataTableSource as any;
+
+const isMounted = ref(false);
+
+// Konfigurasi DataTables: Register core dan extension
+if (typeof window !== "undefined") {
+  DataTableSource.use(DataTablesLib);
+}
+
+// Datatables.net menggunakan API yang sangat dinamis (any is unavoidable here)
+// Semua interaksi publik (props/emits) sudah ditype dengan benar di DataTableMain.vue.d.ts
+
+// ===================================================
+//  Props
+// ===================================================
+interface Props {
+  /** Data array untuk tabel (Alias: dataTableProps) */
+  data?: unknown[];
+  /** Data array untuk tabel (Prop name dari user snippet) */
+  dataTableProps?: unknown[];
+  /** Definisi kolom (Alias: columnsProps) */
+  columns?: Column[];
+  /** Definisi kolom (Prop name dari user snippet) */
+  columnsProps?: Column[];
+  /** Override DataTable options */
+  options?: DataTableOptions;
+  /** Tinggi scroll vertikal (mis: "65vh", "400px") */
+  scrollY?: string | number | false;
+  /** Aktifkan horizontal scroll */
+  scrollX?: boolean;
+  /** Mode responsive (disable scrollX jika aktif) */
+  responsive?: boolean;
+  /** Class CSS tambahan untuk wrapper div */
+  wrapperClass?: string;
+  /** Class CSS tambahan untuk elemen table */
+  tableClass?: string;
+  /** Loading state — tampilkan overlay loading */
+  loading?: boolean;
+  /** Teks loading */
+  loadingText?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  data: () => [],
+  dataTableProps: () => [],
+  columns: () => [],
+  columnsProps: () => [],
+  options: () => ({}),
+  scrollY: "65vh",
+  scrollX: true,
+  responsive: false,
+  wrapperClass: "",
+  tableClass: "",
+  loading: false,
+  loadingText: "Memuat data...",
+});
+
+// Compute internal data and columns from aliases
+const internalData = computed(() =>
+  props.data && props.data.length > 0 ? props.data : props.dataTableProps,
+);
+const internalColumns = computed(() =>
+  props.columns && props.columns.length > 0 ? props.columns : props.columnsProps,
+);
+
+// ===================================================
+//  Emits
+// ===================================================
+const emit = defineEmits<{
+  /** DataTable selesai diinisialisasi */
+  ready: [instance: unknown];
+  /** Tabel selesai di-draw */
+  draw: [settings: unknown];
+  /** Baris di-select */
+  select: [items: unknown[], type: string];
+  /** Baris di-deselect */
+  deselect: [items: unknown[], type: string];
+  /** Error saat inisialisasi */
+  error: [err: Error];
+}>();
+
+// ===================================================
+//  Refs (datatables API requires any)
+// ===================================================
+const containerRef = ref<HTMLElement | null>(null);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const datatableRef = ref<{ dt: any } | null>(null);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let dtInstance: Api<any> | null = null;
+let resizeObserver: ResizeObserver | null = null;
+
+// ===================================================
+//  Computed Options — merge defaultOptions + props
+// ===================================================
+const tableOptions = computed<DataTableOptions>(() => ({
+  ...defaultOptions,
+  scrollY: props.scrollY,
+  scrollX: props.responsive ? false : props.scrollX,
+  responsive: props.responsive,
+  autoWidth: false,
+  deferRender: true,
+  ...props.options,
+}));
+
+// ===================================================
+//  Init
+// ===================================================
+onMounted(async () => {
+  isMounted.value = true;
+  await nextTick();
+
+  if (!datatableRef.value) return;
+
+  try {
+    dtInstance = datatableRef.value.dt;
+    if (!dtInstance) return;
+
+    // Adjust columns setelah mount
+    dtInstance.columns.adjust();
+
+    // Event: ready
+    emit("ready", dtInstance);
+
+    // Event: draw
+    dtInstance.on("draw", (e: Event, settings: unknown) => {
+      emit("draw", settings);
+    });
+
+    // Event: select / deselect (jika pakai select extension)
+    dtInstance.on("select", (_e: Event, _dt: unknown, type: string, indexes: number[]) => {
+      if (!dtInstance) return;
+      const rows = dtInstance.rows(indexes).data().toArray();
+      emit("select", rows, type);
+    });
+
+    dtInstance.on("deselect", (_e: Event, _dt: unknown, type: string, indexes: number[]) => {
+      if (!dtInstance) return;
+      const rows = dtInstance.rows(indexes).data().toArray();
+      emit("deselect", rows, type);
+    });
+
+    // ResizeObserver untuk handle container resize
+    if (containerRef.value) {
+      resizeObserver = new ResizeObserver(() => {
+        if (!dtInstance) return;
+        dtInstance.columns.adjust();
+        setTimeout(() => dtInstance?.columns.adjust(), 150);
+        setTimeout(() => dtInstance?.columns.adjust(), 400);
+      });
+      resizeObserver.observe(containerRef.value);
+    }
+
+    window.addEventListener("resize", handleResize);
+  } catch (err) {
+    emit("error", err instanceof Error ? err : new Error(String(err)));
+  }
+});
+
+// ===================================================
+//  Resize Handler
+// ===================================================
+const handleResize = () => {
+  dtInstance?.columns.adjust();
+};
+
+// ===================================================
+//  Watch: Data changes
+// ===================================================
+watch(
+  () => internalData.value,
+  async (newData) => {
+    if (!dtInstance) return;
+    await nextTick();
+
+    dtInstance.clear();
+
+    if (Array.isArray(newData) && newData.length > 0) {
+      dtInstance.rows.add(newData);
+    }
+
+    dtInstance.draw(false);
+    dtInstance.columns.adjust();
+
+    if (props.responsive) {
+      dtInstance.responsive?.recalc();
+    }
+  },
+  { deep: false },
+);
+
+// ===================================================
+//  Expose public API
+// ===================================================
+defineExpose({
+  /** Dapatkan DataTables instance untuk akses API langsung */
+  getInstance: (): Api<any> | null => dtInstance,
+  /** Reload data secara manual */
+  reload: () => {
+    if (!dtInstance) return;
+    dtInstance.ajax?.reload(undefined, false);
+  },
+  /** Clear & redraw tabel */
+  redraw: () => {
+    if (!dtInstance) return;
+    dtInstance.draw(false);
+  },
+  /** Adjust column widths */
+  adjustColumns: () => {
+    dtInstance?.columns.adjust();
+  },
+});
+
+// ===================================================
+//  Cleanup
+// ===================================================
+onBeforeUnmount(() => {
+  window.removeEventListener("resize", handleResize);
+
+  if (dtInstance) {
+    dtInstance.off("draw");
+    dtInstance.off("select");
+    dtInstance.off("deselect");
+  }
+
+  resizeObserver?.disconnect();
+  resizeObserver = null;
+
+  dtInstance?.destroy(true);
+  dtInstance = null;
+});
+</script>
+
+<template>
+  <div ref="containerRef" :class="['dt-wrapper', wrapperClass]" style="position: relative">
+    <!-- Loading Overlay -->
+    <Transition name="dt-fade">
+      <div v-if="loading" class="dt-loading-overlay">
+        <div class="dt-loading-spinner" />
+        <span class="dt-loading-text">{{ loadingText }}</span>
+      </div>
+    </Transition>
+
+    <DataTableComponent
+      v-if="isMounted"
+      ref="datatableRef"
+      :class="['table', 'table-hover', 'table-bordered', 'table-sm', 'w-100', tableClass]"
+      :columns="internalColumns as any"
+      :data="internalData"
+      :options="tableOptions as unknown as any"
+    >
+      <slot />
+    </DataTableComponent>
+
+    <!-- SSR Fallback: Render a simple table to avoid layout shift -->
+    <table
+      v-else
+      :class="['table', 'table-hover', 'table-bordered', 'table-sm', 'w-100', 'dataTable', tableClass]"
+    >
+      <thead>
+        <tr>
+          <th v-for="col in internalColumns" :key="col.data || col.title">
+            {{ col.title }}
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        <slot />
+      </tbody>
+    </table>
+  </div>
+</template>
+
+<style scoped>
+.dt-wrapper {
+  width: 100%;
+  overflow: hidden;
+}
+
+/* ---- Loading Overlay ---- */
+.dt-loading-overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 10;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-3);
+  background: rgba(255, 255, 255, 0.7);
+  backdrop-filter: blur(4px);
+  border-radius: var(--radius-lg);
+  transition: var(--transition);
+}
+
+.dt-loading-spinner {
+  width: 40px;
+  height: 40px;
+  border: 3px solid var(--bg-mute);
+  border-top-color: var(--primary);
+  border-radius: 50%;
+  animation: dt-spin 0.8s cubic-bezier(0.4, 0, 0.2, 1) infinite;
+}
+
+.dt-loading-text {
+  font-size: var(--fs-sm);
+  color: var(--text-soft);
+  font-weight: var(--fw-medium);
+  letter-spacing: 0.025em;
+}
+
+@keyframes dt-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* ---- Fade Transition ---- */
+.dt-fade-enter-active,
+.dt-fade-leave-active {
+  transition: opacity 0.3s ease;
+}
+
+.dt-fade-enter-from,
+.dt-fade-leave-to {
+  opacity: 0;
+}
+</style>